<body>

<h1>Welcome to the Struts2 DataVision Plugin!</h1>
&copy;2007 Frank W. Zammetti
<hr>
<br><br>

<h2>Introduction</h2>
<br><br>

<h2>Dependencies</h2>
A handful of dependencies must be present on the classpath for the plugin to
work.  These dependency JARs are:
<ul>
  <li>Bean Scripting Framework - bsf.jar (2.4)</li>
  <li>Jakarta Commons Logging - commons-logging.jar (1.1)</li>
  <li>DataVision - DataVision.jar (1.1.0-snapshot-06042007)</li>
  <li>jRuby - jruby.jar (0.9.8)</li>
  <li>Spring Framework Beans Package - spring-beans.jar (2.0.6)</li>
  <li>Spring Framework Core Package - spring-core.jar (2.0.6)</li>
  <li>Spring Framework JDBC Package - spring-jdbc.jar (2.0.6)</li>
  <li>Spring Framework Transactions Package - spring-tx.jar (2.0.6)</li>
</ul>
The numbers in parenthesis are the version numbers that have been tested and
are known to work.  Older or newer versions may or may not work, so use
anything but these versions at your own risk.
<br><br>
In addition, you may require the following dependencies, based on the config
options you choose:
<br>
<ul>
  <li>iText PDF Generation Package - iText.jar (2.0.1)</li>
  <li>POI (Apache MS Office/Excel API) - poi.jar (3.0.alpha3.20061212)</li>
</ul>
<br>

<h2>Configuration</h2>
The plugin makes available a new Result type and a new stack.  The stack is
'datavision-default', which extends 'struts-default'.  The Result type is
'datavision'.  Here is a sample configuration:
<br><br>
<pre>&lt;package name=&quot;default&quot; namespace=&quot;/&quot;
  extends=&quot;datavision-default&quot;&gt;
  &lt;action name=&quot;runReport&quot; class=&quot;app.RunReportAction
  &quot;&gt;
    &lt;result name=&quot;success&quot; type=&quot;datavision&quot;&gt;
      &lt;param name=&quot;dvTemplate&quot;&gt;/WEB-INF/report_template.xml
      &lt;/param&gt;
      &lt;param name=&quot;dvParameters&quot;&gt;age&lt;/param&gt;
      &lt;param name=&quot;dvOutputType&quot;&gt;html&lt;/param&gt;
      &lt;param name=&quot;dvOutputDisposition&quot;&gt;&lt;/param&gt;
      &lt;param name=&quot;dvOutputFilename&quot;&gt;&lt;/param&gt;
      &lt;param name=&quot;dvDataSourceType&quot;&gt;create&lt;/param&gt;
      &lt;param name=&quot;dvDriverClass&quot;&gt;
      org.apache.derby.jdbc.EmbeddedDriver&lt;/param&gt;
      &lt;param name=&quot;dvConnString&quot;&gt;jdbc:derby:dvplugin
      &lt;/param&gt;
      &lt;param name=&quot;dvUsername&quot;&gt;&lt;/param&gt;
      &lt;param name=&quot;dvPassword&quot;&gt;&lt;/param&gt;
      &lt;param name=&quot;dvJNDIName&quot;&gt;&lt;/param&gt;
      &lt;param name=&quot;dvJNDIContext&quot;&gt;&lt;/param&gt;
    &lt;/result&gt;
  &lt;/action&gt;
&lt;/package&gt;</pre>
Here you can see that there are a number of configuration parameters available.
<ul>
  <li>
    <b>dvTemplate</b> - THIS IS REQUIRED.  This is the context-relative path to
    the report template XML file.  Note that while this is a required parameter,
    you can still specify it other ways, as detailed in the comments following
    this list.
  </li>
  <br><br>
  <li>
    <b>dvParameters</b> - This is the comma-separated list of parameters the
    report supports (if any).  Note that the names listed here must match
    exactly, including case, how they are specified in the report template.
  </li>
  <br><br>
  <li>
    <b>dvOutputType</b> - This is the type of output to generate.  Valid values
    are "html", "pdf", "docbook", "delimited", "excel" and "latex".
    These correspond to the available layout engines provided by DataVision.
    This parameter will default to "html" if not specified.
  </li>
  <br><br>
  <li>
    <b>dvOutputDisposition</b> - This is the way the output should be delivered
    to the browser.  Valid values are "inline" and "attachment".  When it's
    "inline", the response will be streamed back to the client to handle,
    typically with whatever plugin handles the content type.  When it's
    "attachment", the user will be prompted with a download dialog.
    This parameter will default to "inline" if not specified.
  </li>
  <br><br>
  <li>
    <b>dvOutputFilename</b> - When dvOutputDisposition=="attachment", this
    parameter specified the default filename the download dialog will offer to
    the user. This is ignored when dvOutputDisposition=="inline".  This
    parameter will default to "output.xxx" if not specified, where .xxx will be
    "pdf" for dvOutputType=="pdf", "latex" for dvOutpuType=="latex", "txt" for
    dvOutputType=="delimited", "xml" for dvOutputType=="docbook", "html" for
    dvOutputType=="html" and "xls" for dvOutputType="excel".  Note that when you
    specify a value, you should NOT include an extension because the extension
    will automatically be appended to whatever you specify here.
  </li>
  <br><br>
    <b>dvDelimiter</b> - When dvOutputType=="delimited", this parameter
    specifies the delimiter character to use.  This parameter will default to
    comma if not specified.
  </li>
  <br><br>
  <li>
    <b>dvDataSourceType</b> - This is how the DataSource object the report will
    use will be gotten.  Valid values are "managed", "create" and "manual".
    This parameter will default to "manual" if not specified.  Here is the
    meaning of each:
    <br><br>
    <ul>
      <li>
        "<i>manual</i>" - Your code is taking responsibility for supplying a
        DataSource to the Result.  Any other dv* parameters present will be
        ignored.  An object under the name "dvDataSource" will be where the JDBC
        DataSource object is found.
      </li>
      <li>
        "<i>managed</i>" - The DataSource will be retrieved from the container
        via JNDI lookup.  When this is used, dvJNDIName becomes require, and
        dvJNDIContext may or may not be used.
      </li>
      <li>
        "<i>create</i>" - The DataSource will be instantiated with each
        execution.  When this is used, The dvDriverClass and dvConnString
        parameters are required.  The dvUsername and dvPassword parameters may
        or may not be used.
      </li>
    </ul>
  </li>
  <br>
  <li>
    <b>dvJNDIName</b> - This is required when dataSource=="managed", otherwise
    it will be ignored.  This is the name in JNDI under which the DataSource
    is found.
  </li>
  <br><br>
  <li>
    <b>dvJNDIContext</b> - When dataSource=="managed", this parameter comes into
    play, otherwise it will be ignored.  This is the name of the context under
    which dvJDNIName will be found.  If this parameter is not present, the
    InitialContext will be used.
  </li>
  <br><br>
  <li>
    <b>dvDriverClass</b> - This is required when dataSource=="create", otherwise
    it will be ignored.  This is the fully-qualified name of the JDBC driver
    class that will be used to access the database.
  </li>
  <br><br>
  <li>
    <b>dvConnString</b> - This is required when dataSource=="create", otherwise
    it will be ignored. This is the JDBC connection string used to connect to
    the database.
  </li>
  <br><br>
  <li>
    <b>dvUsername</b> - When dataSource="create", this parameter potentially
    comes into play, otherwise it will be ignored.  This is the username used to
    connect to the database.
  </li>
  <br><br>
  <li>
    <b>dvPassword</b> - When dataSource="create", this parameter potentially
    comes into play, otherwise it will be ignored.  This is the password of the
    user used to connect to the database.
  </li>
</ul>
<br>

<h2>Notes</h2>
For all of these parameters, you can specify their values in a couple of ways.
One is to supply them as parameters of the Result.  Another way is to provide
the parameter value via the ValueStack.  When a given parameter is not present
in the Result config itself, the ValueStack is consulted using the same name as
the parameter.  If found, that value will be used.  Typically, you would have a
member and associated getter on your Action with a name matching that of the
parameter, but it will still be retrieve via the ValueStack in that case.
<br><br>
Note that the value on the Result itself will always take precendence if it is
set on the ValueStack as well.
<br><br>
Also note that of all the parameter, only the dvTemplate parameter MUST be
supplied in one fashion or another, the rest have reasonable defaults which can
be used.
<br><br>
When the dvDataSourceType == "manual", a JDBC DataSource object must be
available on the ValueStack under the name "dvDataSource".  This is usually
done with a getter getDataSource() on the Action, but it's up to you.

<br><br>

</body>